Skip to content

Add method="auto", which chooses a method for each distance search, and make it the default - #913

Merged
perlinm merged 7 commits into
mainfrom
feat/auto-distance-method
Nov 16, 2026
Merged

perlinm merged 7 commits into
mainfrom
feat/auto-distance-method

Conversation

@perlinm

@perlinm perlinm commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Motivation

The two exact distance searches of qLDPC win on different codes, often by large factors. The connected-cluster search is far faster than the Brouwer-Zimmermann (BZ) search on many quantum LDPC codes, but much slower on some others, and on classical codes whose checks are only moderately sparse. A user should not have to know which method suits a code.

Changes

  • method="auto" chooses a method for each search, and becomes the default of the distance functions of qldpc.codes.distance, of get_distance and get_distance_exact of the code classes, of get_fault_distance, and of the deprecated get_distance_classical and get_distance_quantum. The rule is a heuristic, not fitted, which aims to avoid a very slow method rather than to find the fastest: brute force if that is cheap, BZ for classical codes and for functions that take generators, and otherwise a connected-cluster search, which a short BZ probe may finish or cap, and which switches to BZ if BZ is predicted to cost less. The section "Choosing a method" of src/qldpc/codes/distance/README.md states the rule, argues that results stay exact, and lists its known losses. Coset searches keep BZ, which they also take for "auto".
  • The new _auto.py holds the rule, and core.py routes each kind of search to it. The steppable searches of Step the BZ and connected-cluster searches of several problems through resumable objects #900 gain hooks that report their work and progress, and _tuning.py gains four fields, documented in docs/source/exact_search_tuning.rst.
  • Tests, notebooks, and documentation that assumed BZ as the default now pass method="brouwer_zimmermann", or no longer say so.

Validation

The rule and its budgets came from a study outside the repository, and were checked on held-out codes before implementation. The times below are from an earlier revision of this branch; the routes that "auto" takes on 13 recorded workloads have not changed since.

On the X sectors of 118 quantum codes (bivariate-bicycle, lifted-product, and quantum Tanner codes), "auto" took 1726 s in total, against 1990 s for the faster method on each code, and 6574 s for BZ, plus 18 searches that BZ did not finish within 300 s or 900 s. No code took "auto" both twice as long as the faster method and at least 1 s longer; the largest excess was 2.3 s. On other kinds of search, with a limit of 300 s:

Case "auto" BZ connected-cluster
Hadamards on half of the gross code (not CSS) 0.31 s 151 s 0.21 s
Hadamards on half of lp13s5 1.83 s >300 s 1.78 s
Fault distance, one round of the gross code 12.2 s >300 s 12.0 s
Classical [128, 48] code 0.63 s 0.64 s >300 s

Explicit "brouwer_zimmermann" and "connected_cluster" searches are unchanged: on ten workloads, experiments/distance_tuning/trace.py --compare finds the same decisions as on main, and sweep.py --worktrees gives median ratios of 0.97 to 1.03 to main's times.

Additional notes

  • The default changes without a FutureWarning, since results are exact either way. With a cutoff of 2 or more, the weight returned can depend on the method, within the documented contract.
  • "auto" can take up to about a second longer than BZ on searches that BZ finishes at once, such as of random codes of about 60 bits, which it enumerates or probes.
  • On quantum codes and circuits, "auto" runs connected-cluster searches, which take a keyboard interrupt only between weight limits.

perlinm and others added 7 commits November 16, 2026 15:54
…nd make it the default

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Test that searches by cost check and lift automorphisms on their CSS and
connected-cluster sides, and that stepped connected-cluster searches add the
states of their sectors and grow per unit of weight.  Restructure _search_css
around a helper for the sparser sectors of a connected-cluster search, and
clarify docstrings, comments, and error messages that omitted "auto".

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…m to "auto"

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…han mock it

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…hresholds

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@perlinm
perlinm merged commit 0f8f058 into main Nov 16, 2026
9 checks passed
@perlinm
perlinm deleted the feat/auto-distance-method branch November 16, 2026 22:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant